Эта страница переведена с помощью Cloud Translation API.

Поворот рекламных объявлений с помощью API Select URL
Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Используйте API Select URL, чтобы воспользоваться преимуществами общего хранилища и определить, какие креативы видит пользователь на разных сайтах.

Рекламодатель или производитель контента может захотеть применить различные стратегии ротации контента к кампании и ротировать контент или креативы для повышения эффективности. API Select URL можно использовать для запуска различных стратегий ротации, таких как последовательная ротация и равномерно распределенная ротация, на разных сайтах.

С помощью ротации креативов Select URL API вы можете хранить такие данные, как идентификатор креатива, количество просмотров и взаимодействие с пользователем, чтобы определить, какие креативы пользователи видят на разных сайтах.

Для получения дополнительной информации о базовом API и о том, как работает выбор, изучите документацию по API Select URL .

Попробуйте креативную ротацию

Чтобы поэкспериментировать с ротацией креативов, убедитесь, что Select URL API и Shared Storage включены:

В chrome://settings/content/siteData выберите Allow sites to save data on your device или Delete data sites have saved to your device when you close all windows .
В chrome://settings/adPrivacy/sites выберите Site-suggested ads .

Попробуйте нашу интерактивную демонстрацию общего хранилища, чтобы ознакомиться с реальной версией примеров кода из этого документа.

Демонстрация с примерами кода

В этом примере:

creative-rotation.js — это сторонний скрипт, определяющий содержимое, которое должно быть ротировано, а также любые данные, которые определяют следующее содержимое для выбора и отображения, например, веса в этом примере. Страница издателя выполняет этот скрипт. Этот скрипт вызывает общий рабочий класс хранилища, чтобы определить, какой контент отображать на основе доступных данных в хранилище и списка URL-адресов для выбора.
creative-rotation-worklet.js — это сторонний ворклет общего хранилища, который ищет стратегию ротации, вычисляет, какой контент опубликовать следующим, и возвращает этот фрагмент контента.

Как работает демо

Когда пользователь посещает страницу издателя, страница загружает скрипт creative-rotation.js третьей стороны. Скрипт ротации креативов отвечает за загрузку и запуск общего хранилища ворклета. Скрипт предоставляет вызову ворклета список URL-адресов для выбора.
В ворклете, если общее хранилище еще не инициализировано, хранилище инициализируется с начальной стратегией творческой ротации и творческим индексом. Начальная стратегия ротации, используемая в этой демонстрации, — это последовательная стратегия.
Worklet считывает режим ротации из общего хранилища и возвращает индекс следующего объявления. В случае последовательного режима ротации он также обновляет индекс креатива в общем хранилище новым значением, которое будет использоваться для следующего вызова. Worklet возвращает FencedFrameConfig или непрозрачный объект URN на основе значения resolveToConfig , используемого при вызове selectURL .
Скрипт вращения креатива отображает выбранное объявление в Fenced Frame или iframe. Подробности о типах возврата см. в документе render an ad.
Когда пользователь меняет режим вращения, рабочий модуль общего хранилища обновляет значение режима творческого вращения, сохраненное в общем хранилище.
При перезагрузке страницы издателя шаги 1–4 повторяются, что позволяет выбрать следующее объявление для просмотра на основе выбранной стратегии ротации.

Примеры кода

Ниже приведены примеры кода для creative-rotation.js и creative-rotation-worklet.js .

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Пошаговое руководство со скриншотами

Чтобы получить доступ к ротации креативов с помощью Select URL API и общего хранилища, перейдите по адресу https://shared-storage-demo.web.app/ . Выберите демо «Creative Rotation».
Выберите для изучения демоверсию как «Издатель А». Вы будете перенаправлены на https://shared-storage-demo-publisher-a.web.app/creative-rotation . Страница загружает пронумерованный контент на основе данных ротации креативов, сохраненных в общем хранилище, доступ к которому осуществляется через API Select URL. Демонстрационные режимы ротации креативов — последовательное, равномерное распределение и взвешенное распределение. Ворклет выполняет логику для выбора контента, который отображается в iframe. На следующем изображении показана страница издателя.
На снимке экрана показана страница издателя A с изображением цифры 1 и элементами управления для выбора стратегий ротации креативов.
Чтобы просмотреть, что хранится в общем хранилище, перейдите в Application -> Shared Storage в Chrome DevTools. Для общего хранилища создаются две записи. Для источника https://shared-storage-demo-publisher-a.web.app доступно пустое хранилище. Оно будет содержать хранилище, специфичное для этого источника, и останется пустым для нашей демонстрации, поскольку издателю не нужно записывать в общее хранилище. Обратите внимание, что аналогичное хранилище будет создано для издателя B, когда вы посетите эту страницу позже для демонстрации.
Chrome DevTools показывает пустое общее хранилище для издателя A.
Еще одна запись общего хранилища будет создана для https://shared-storage-demo-content-producer.web.app источника. Это хранилище стороннего iframe, встроенного на страницу издателя. Это хранилище будет использоваться для обмена данными между двумя доступными издателями для координации выбора креативов. Это общее хранилище будет использоваться для сохранения информации о показанном креативе и стратегии ротации путем сохранения двух пар ключ-значение. Первый ключ, используемый в демонстрации, — creative-rotation-index , значение которого — текущий индекс креатива в последовательном режиме. Второй ключ — creative-rotation-mode , который определяет используемую стратегию ротации.
На снимке экрана показано общее хранилище Chrome DevTools с двумя парами ключ-значение: creative-rotation-index: 1 и creative-rotation-mode: "sequential".
Обновление страницы в последовательном режиме приведет к отображению следующего креатива в последовательности 1, 2, 3, 1, …. Значение ключа creative-rotation-index будет изменяться в соответствии с индексом отображаемого креатива в последовательном режиме.
Скриншот показывает веб-страницу и DevTools издателя A. Показанный креатив — 2, creative-rotation-mode — последовательный, а creative-rotation-index — 2.
Изменение режима вращения креатива с помощью кнопок управления обновит значение ключа creative-rotation-mode в соответствующую стратегию. Это будет использоваться кодом ворклета для выбора следующего креатива для показа в iframe. Обратите внимание, что значение, сохраненное для creative-rotation-index, не изменяется для режимов вращения, отличных от последовательного.
Скриншот показывает веб-страницу и DevTools издателя A. Показанный креатив — 1, creative-rotation-mode — взвешенное распределение, а creative-rotation-index — 2 (не используется).
Перейдите на страницу для "Publisher B" по адресу https://shared-storage-demo-publisher-b.web.app/creative-rotation . В последовательном режиме показанный креатив должен быть следующим креативом в последовательности, показанной при посещении URL для "Publisher A". Проверяя общее хранилище для производителя контента, вы можете обнаружить, что и "Publisher A", и "Publisher B" совместно используют одно и то же хранилище и используют настройки там для выбора следующего креатива для показа и стратегии ротации для использования.
Веб-страница и DevTools издателя B. Креатив общего хранилища — 3, индекс ротации креативов — 3, а режим ротации креативов — последовательный.
Общее хранилище для «Издателя B» пусто, как и общее хранилище для «Издателя A».
Chrome DevTools показывает пустое общее хранилище для источника издателя B.

Варианты использования
Все доступные варианты использования Select URL API можно найти в этом разделе. Мы продолжим добавлять примеры по мере получения отзывов и обнаружения новых тестовых случаев.
- Чередуйте рекламные объявления : сохраняйте данные, такие как идентификатор креатива и взаимодействие с пользователем, чтобы определить, какие креативы пользователи видят на разных сайтах.
- Выберите рекламные объявления по частоте : используйте данные о количестве просмотров, чтобы определить, какие креативы видят пользователи на разных сайтах.
- Запустите A/B-тестирование : вы можете назначить пользователя в экспериментальную группу, а затем сохранить эту группу в общем хранилище для обеспечения кросс-сайтового доступа.
- Персонализируйте опыт для известных клиентов : делитесь индивидуальным контентом и призывами к действию на основе статуса регистрации пользователя или других состояний пользователя.

Привлекайте и делитесь отзывами

Обратите внимание, что предложение Select URL API находится в стадии активного обсуждения и разработки и может быть изменено.

Мы хотим услышать ваши мысли об API выбора URL.

Предложение : Рассмотрите подробное предложение .
Обсуждение : присоединяйтесь к продолжающемуся обсуждению , чтобы задавать вопросы и делиться своими мыслями.

Будьте в курсе

Список рассылки : подпишитесь на нашу рассылку , чтобы получать последние обновления и объявления, связанные с API выбора URL-адреса и общего хранилища.

Нужна помощь?

Поддержка разработчиков : общайтесь с другими разработчиками и получайте ответы на свои вопросы в репозитории поддержки разработчиков Privacy Sandbox .